

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>Image Encryption &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />

  
  
    <link rel="shortcut icon" href="../../_static/favicon.ico"/>
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/underscore.js"></script>
        <script src="../../_static/doctools.js"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="配置选项" href="../rbd-config-ref/" />
    <link rel="prev" title="RBD Persistent Write Log Cache" href="../rbd-persistent-write-log-cache/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    

















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../../" class="icon icon-home"></a> &raquo;</li>
        
          <li><a href="../">Ceph 块设备</a> &raquo;</li>
        
          <li><a href="../rbd-operations/">Ceph 块设备运维</a> &raquo;</li>
        
      <li>Image Encryption</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../../_sources/rbd/rbd-encryption.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../">
          

          
            
            <img src="../../_static/logo.png" class="logo" alt="Logo"/>
          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../start/intro/">Ceph 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../">Ceph 块设备</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../rados-rbd-cmds/">基本命令</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../rbd-operations/">运维</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../rbd-snapshot/">快照</a></li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-exclusive-locks/">互斥锁、独占锁</a></li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-mirroring/">镜像</a></li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-live-migration/">实时迁移</a></li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-persistent-read-only-cache/">永久只读缓存</a></li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-persistent-write-log-cache/">永久写日志缓存</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">加密</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#encryption-format">Encryption Format</a></li>
<li class="toctree-l4"><a class="reference internal" href="#encryption-load">Encryption Load</a></li>
<li class="toctree-l4"><a class="reference internal" href="#supported-formats">Supported Formats</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-config-ref/">配置选项 (librbd)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../rbd-replay/">RBD 重放</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../rbd-integrations/">对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../man/">手册页</a></li>
<li class="toctree-l2"><a class="reference internal" href="../api/">APIs</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../radosgw/">Ceph 对象网关</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <div class="section" id="image-encryption">
<h1>Image Encryption<a class="headerlink" href="#image-encryption" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Starting with the Pacific release, image-level encryption can be handled
internally by RBD clients. This means you can set a secret key that will be
used to encrypt a specific RBD image. This page describes the scope of the
RBD encryption feature.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <code class="docutils literal notranslate"><span class="pre">krbd</span></code> kernel module does not support encryption at this time.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>External tools (e.g. dm-crypt, QEMU) can be used as well to encrypt
an RBD image, and the feature set and limitation set for that use may be
different than described here.</p>
</div>
<div class="section" id="encryption-format">
<h2>Encryption Format<a class="headerlink" href="#encryption-format" title="Permalink to this headline">¶</a></h2>
<p>By default, RBD images are not encrypted. To encrypt an RBD image, it needs to
be formatted to one of the supported encryption formats. The format operation
persists encryption metadata to the image. The encryption metadata usually
includes information such as the encryption format and version, cipher
algorithm and mode specification, as well as information used to secure the
encryption key. The encryption key itself is protected by a user-kept secret
(usually a passphrase), which is never persisted. The basic encryption format
operation will require specifying the encryption format and a secret.</p>
<p>Some of the encryption metadata may be stored as part of the image data,
typically an encryption header will be written to the beginning of the raw
image data. This means that the effective image size of the encrypted image may
be lower than the raw image size. See the <a class="reference external" href="#supported-formats">Supported Formats</a> section for more
details.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Currently only flat images (i.e. not cloned) can be formatted.
Clones of an encrypted image are inherently encrypted using the same format
and secret.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Any data written to the image prior to its format may become unreadable,
though it may still occupy storage resources.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Images with the <a class="reference external" href="../rbd-mirroring/#enable-image-journaling-feature">journal feature</a> enabled cannot be formatted and encrypted
by RBD clients.</p>
</div>
</div>
<div class="section" id="encryption-load">
<h2>Encryption Load<a class="headerlink" href="#encryption-load" title="Permalink to this headline">¶</a></h2>
<p>Formatting an image is a necessary pre-requisite for enabling encryption.
However, formatted images will still be treated as raw unencrypted images by
all of the RBD APIs. In particular, an encrypted RBD image can be opened
by the same APIs as any other image, and raw unencrypted data can be
read / written. Such raw IOs may risk the integrity of the encryption format,
for example by overriding encryption metadata located at the beginning of the
image.</p>
<p>In order to safely perform encrypted IO on the formatted image, an additional
<em>encryption load</em> operation should be applied after opening the image. The
encryption load operation requires supplying the encryption format and a secret
for unlocking the encryption key. Following a successful encryption load
operation, all IOs for the opened image will be encrypted / decrypted.
For a cloned image, this includes IOs for ancestor images as well. The
encryption key will be stored in-memory by the RBD client until the image is
closed.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Once encryption has been loaded, no other encryption load / format
operations can be applied to the context of the opened image.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Once encryption has been loaded, API calls for retrieving the image size
using the opened image context will return the effective image size.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Encryption load can be automatically applied when mounting RBD images as
block devices via <a class="reference external" href="../../man/8/rbd-nbd">rbd-nbd</a>.</p>
</div>
</div>
<div class="section" id="supported-formats">
<h2>Supported Formats<a class="headerlink" href="#supported-formats" title="Permalink to this headline">¶</a></h2>
<div class="section" id="luks">
<h3>LUKS<a class="headerlink" href="#luks" title="Permalink to this headline">¶</a></h3>
<p>Both LUKS1 and LUKS2 are supported. The data layout is fully compliant with the
LUKS specification. Thus, images formatted by RBD can be loaded using external
LUKS-supporting tools such as dm-crypt or QEMU. Furthermore, existing LUKS
data, created outside of RBD, can be imported (by copying the raw LUKS data
into the image) and loaded by RBD encryption.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The LUKS formats are supported on Linux-based systems only.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Currently, only AES-128 and AES-256 encryption algorithms are supported.
Additionally, xts-plain64 is currently the only supported encryption mode.</p>
</div>
<p>To use the LUKS format, start by formatting the image:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ rbd encryption format {pool-name}/{image-name} {luks1|luks2} {passphrase-file} [–cipher-alg {aes-128 | aes-256}]
</pre></div>
</div>
<p>The encryption format operation generates a LUKS header and writes it to the
beginning of the image. The header is appended with a single keyslot holding a
randomly-generated encryption key, and is protected by the passphrase read from
<cite>passphrase-file</cite>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the content of <cite>passphrase-file</cite> ends with a newline character, it will
be stripped off.</p>
</div>
<p>By default, AES-256 in xts-plain64 mode (which is the current recommended mode,
and the usual default for other tools) will be used. The format operation
allows selecting AES-128 as well. Adding / removing passphrases is currently
not supported by RBD, but can be applied to the raw RBD data using compatible
tools such as cryptsetup.</p>
<p>The LUKS header size can vary (upto 136MiB in LUKS2), but is usually upto
16MiB, depending on the version of <cite>libcryptsetup</cite> installed. For optimal
performance, the encryption format will set the data offset to be aligned with
the image object size. For example expect a minimum overhead of 8MiB if using
an imageconfigured with an 8MiB object size.</p>
<p>In LUKS1, sectors, which are the minimal encryption units, are fixed at 512
bytes. LUKS2 supports larger sectors, and for better performance we set
the default sector size to the maximum of 4KiB. Writes which are either smaller
than a sector, or are not aligned to a sector start, will trigger a guarded
read-modify-write chain on the client, with a considerable latency penalty.
A batch of such unaligned writes can lead to IO races which will further
deteriorate performance. Thus it is advisable to avoid using RBD encryption
in cases where incoming writes cannot be guaranteed to be sector-aligned.</p>
<p>To mount a LUKS-encrypted image run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ rbd -p {pool-name} device map -t nbd -o encryption-format={luks1|luks2},encryption-passphrase-file={passphrase-file}
</pre></div>
</div>
<p>Note that for security reasons, both the encryption format and encryption load
operations are CPU-intensive, and may take a few seconds to complete. For the
encryption operations of actual image IO, assuming AES-NI is enabled,
a relative small microseconds latency should be added, as well as a small
increase in CPU utilization.</p>
</div>
</div>
</div>



           </div>
           
          </div>
          <footer>
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
        <a href="../rbd-config-ref/" class="btn btn-neutral float-right" title="配置选项" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
        <a href="../rbd-persistent-write-log-cache/" class="btn btn-neutral float-left" title="RBD Persistent Write Log Cache" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>
        &#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).

    </p>
  </div> 

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>